home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / Gen_String.3T < prev    next >
Text File  |  1992-06-26  |  20KB  |  516 lines
  1. .TH GEN_STRING
  2. .SH NAME
  3. Gen_String  Dynamic general-purpose strings with reference counting, delayed copy, and regular expression pattern matching
  4. .SH SYNOPSIS
  5. \f3#include \f1<cool/Gen_String.h>
  6. .SH DESCRIPTION
  7. The 
  8.  Gen_String 
  9. class provides general-purpose, dynamic strings for a \f3C++\f1
  10. application with support for reference counting, delayed copy, and regular 
  11. expression pattern matching. The intent is to provide sophisticated character 
  12. string functionality for the application programmer.  As in the \f3String\f1 class, 
  13. interface and member functions provide typical string operations. These include 
  14. concatenation, case-sensitive and case-insensitive lexical comparison, string 
  15. search, yank, delete, and replacement. In addition, the inclusion of regular 
  16. expression pattern matching facilitates easier use of this cool class with 
  17. character strings. The 
  18.  Gen_String 
  19. class is dynamic in the sense that if an 
  20. operation such as concatenate results in more characters than can fit in the 
  21. currently allocated memory, the string object \f2grows\f1 according to some 
  22. established size or ratio value.
  23. .SH Base Classes
  24.  
  25. .SH Friend Classes
  26. None
  27. .SH Constructors
  28. .TP
  29.  Gen_String ();
  30. Initializes an empty general string object with the default size block of 
  31. memory allocated to hold 100 characters.
  32. .TP
  33. \f3Gen_String (char \f2c\f3);\f1
  34. Initializes a general string object with the default size block of memory 
  35. allocated to hold 100 characters whose value is the general string consisting 
  36. of the single character
  37.  c .
  38. .TP
  39. \f3Gen_String (const char* \f2str\f3);\f1
  40. Initializes a general string object with a default size block of memory 
  41. allocated to hold 100 characters whose value is a copy of the specified 
  42. character string argument 
  43.  str . 
  44. If \f2str\f1 is longer than 100 char then the
  45.  Gen_String 
  46. will grow to the correct size.
  47. .TP
  48. \f3Gen_String (const char* \f2str\f3, long \f2size\f3);\f1
  49. Allocates an initial block of memory of size \f2size\f1 or size \f3strlen\f2(str)\f1 whichever 
  50. is longer.  Initializes the general string object with a copy of the specified 
  51. character string \f2str\f1. 
  52. .TP
  53. \f3Gen_String (const Gen_String& \f2str\f3);\f1
  54. Duplicates the size and value of another general string object \f2str\f1.
  55. .TP
  56. \f3Gen_String (const Gen_String& \f2str\f3, long \f2size\f3);\f1
  57. Duplicates the 
  58.  size 
  59. and value of another general string object 
  60.  str 
  61. and 
  62. allocates an initial block of memory of size 
  63.  size 
  64. or size \f3strlen\f2(str)\f1 whichever 
  65. is longer. 
  66. .SH Member Functions
  67. .TP
  68.  inline long capacity () const;
  69. Returns the maximum number of characters that the general string object can 
  70. contain without having to grow.
  71. .TP
  72.  void clear ();
  73. Resets the 
  74.  
  75.  NULL 
  76. character sting terminator to the beginning of the general 
  77. string and sets the length of the general string to zero.
  78.  
  79. .TP
  80. \f3void compile (char* \f2str\f3);\f1
  81. Creates a compiled version of the regular expression argument \f2str\f1. If an 
  82. invalid expression is detected, an \f3\f3Error\f1\f1 exception is raised. Note that you 
  83. must recompile a regular expression after changing the value of the \f3Gen_String\f1 object.
  84. .TP
  85.  inline long end () const;
  86. Returns an index into the last string successfully searched for by this object. 
  87. The index corresponds to the character after the last item found, or if none 
  88. was found (the uninitialized state) then its value is \f3NULL\f1.
  89. .TP
  90.  Boolean find ();
  91. Searches for the first or next established regular expression in the string. If 
  92. the expression is found, this function returns \f3TRUE\f1
  93. and sets start and end 
  94. appropriately. If an invalid expression is detected, an \f3\f3Error\f1\f1 exception is 
  95. raised.
  96. .TP
  97. \f3Boolean insert (const char* \f2str\f3, long \f2position\f3);\f1
  98. Inserts a copy of the sequence of characters 
  99.  str 
  100. at the zero-relative index 
  101. \f2position\f1. This function returns \f3TRUE\f1 if successful; otherwise, this function 
  102. returns \f3FALSE\f1 if the index 
  103.  position 
  104. is out of range.
  105. .TP
  106.  inline Boolean is_valid () const;
  107. Returns \f3TRUE\f1 if a valid regular expression is compiled and ready for use; 
  108. otherwise, this function returns \f3FALSE\f1.
  109. .TP
  110. \f3Gen_String operator+ (char \f2c\f3);\f1
  111. Overloads the addition operator to concatenate a single character 
  112.  c 
  113. to a general string object. This function returns a new general string object.
  114. .TP
  115. \f3Gen_String operator+ (const char* \f2str\f3);\f1
  116. Overloads the addition operator to concatenate a copy of the character sequence 
  117. \f2str\f1 to a general string object. This function returns a new general string object. 
  118. .TP
  119. \f3Gen_String operator+ (const Gen_String& \f2str\f3);\f1
  120. Overloads the addition operator to concatenate the value of another general 
  121. string object \f2str\f1 to a general string object. This function returns a new 
  122. general string object.
  123. .TP
  124. \f3inline Gen_String& operator= (char \f2c\f3);\f1
  125. Overloads the assignment operator to assign a single character \f2c\f1 to a general 
  126. string object.  This function returns a reference to the modified general 
  127. string object.
  128. .TP
  129. \f3inline Gen_String& operator= (const char* \f2str\f3);\f1
  130. Overloads the assignment operator to assign a copy of the character sequence 
  131. \f2str\f1 to a general string object.  This function returns a reference to the 
  132. modified general string object.  
  133. .TP
  134. \f3inline Gen_String& operator= (const Gen_String& \f2str\f3);\f1
  135. Overloads the assignment operator to assign the value of another general string 
  136. object \f2str\f1 to a general string object.  This function returns a reference to 
  137. the modified general string object. 
  138. .TP
  139. \f3Gen_String& operator+= (char \f2c\f3);\f1
  140. Overloads the addition-and-assignment operator to concatenate a single 
  141. character \f2c\f1 to a general string object. This function returns a reference to 
  142. the modified general string object. 
  143. .TP
  144. \f3Gen_String& operator+= (const char* \f2str\f3);\f1
  145. Overloads the addition-and-assignment operator to concatenate a copy of the 
  146. character sequence \f2str\f1 to a general string object. This function returns 
  147. a reference to the modified general string object.
  148.  
  149. .TP
  150. \f3Gen_String& operator+= (const Gen_String& \f2str\f3);\f1
  151. Overloads the addition-and-assignment operator to concatenate the value of 
  152. another general string object \f2str\f1 to a general string object. This function returns a reference to the modified general string object.
  153. .TP
  154. \f3inline Boolean operator== (const char* \f2str\f3) const;\f1
  155. Overloads the equality operator for the 
  156.  Gen_String 
  157. class. This function returns 
  158. \f3TRUE\f1 if the general string object and \f2str\f1 have the same sequence of characters; 
  159. otherwise, this function returns \f3FALSE\f1.
  160. .TP
  161. \f3inline Boolean operator== (const Gen_String& \f2str\f3) const;\f1
  162. Overloads the equality operator for the 
  163.  Gen_String 
  164. class. This function returns 
  165. \f3TRUE\f1 if the general strings have the same sequence of characters; otherwise, 
  166. this function returns \f3FALSE\f1.
  167. .TP
  168. \f3inline Boolean operator!= (const char* \f2str\f3) const;\f1
  169. Overloads the inequality operator for the 
  170.  Gen_String 
  171. class. This function 
  172. returns \f3FALSE\f1 if the general string object and \f2str\f1 have the same sequence of 
  173. characters; otherwise, this function returns \f3TRUE\f1.
  174. .TP
  175. \f3inline Boolean operator!= (const Gen_String& \f2str\f3) const;\f1
  176. Overloads the inequality operator for the 
  177.  Gen_String 
  178. class. This function 
  179. returns \f3FALSE\f1 if the general strings have the same sequence of characters; 
  180. otherwise, this function returns \f3TRUE\f1.
  181. .TP
  182. \f3inline Boolean operator< (const char* \f2str\f3) const;\f1
  183. Overloads the less-than operator for the 
  184.  Gen_String 
  185. class. This function 
  186. returns \f3TRUE\f1 if the general string object is lexically less than \f2str\f1\^; 
  187. otherwise, this function returns \f3FALSE\f1.
  188. .TP
  189. \f3inline Boolean operator< (const Gen_String& \f2str\f3) const;\f1
  190. Overloads the less-than operator for the 
  191.  Gen_String 
  192. class. This function 
  193. returns \f3TRUE\f1 if the general string object is lexically less than \f2str\f1\^; 
  194. otherwise, this function returns \f3FALSE\f1.
  195. .TP
  196. \f3inline Boolean operator<= (const char* \f2str\f3) const;\f1
  197. Overloads the less-than-or-equal operator for the 
  198.  Gen_String 
  199. class. This 
  200. function returns 
  201.  
  202.  TRUE 
  203. if the general string object is lexically less than or 
  204. equal to \f2str\f1\^; otherwise, this function returns 
  205.  
  206.  FALSE .
  207. .TP
  208. \f3inline Boolean operator<= (const Gen_String& \f2str\f3) const;\f1
  209. Overloads the less-than-or-equal operator for the 
  210.  Gen_String 
  211. class. This 
  212. function returns \f3TRUE\f1 if the general string object is lexically less than or 
  213. equal to \f2str\f1\^; otherwise, this function returns \f3FALSE\f1.
  214. .TP
  215. \f3inline Boolean operator> (const char* \f2str\f3) const;\f1
  216. Overloads the greater-than operator for the 
  217.  Gen_String 
  218. class. This function 
  219. returns \f3TRUE\f1 if the general string object is lexically greater than \f2str\f1\^; 
  220. otherwise, this function returns \f3FALSE\f1.
  221. .TP
  222. \f3inline Boolean operator> (const Gen_String& \f2str\f3) const;\f1
  223. Overloads the greater-than operator for the 
  224.  Gen_String 
  225. class. This function 
  226. returns \f3TRUE\f1 if the general string object is lexically greater than \f2str\f1\^; 
  227. otherwise, this function returns \f3FALSE\f1.
  228. .TP
  229. \f3inline Boolean operator>= (const char* \f2str\f3) const;\f1
  230. Overloads the greater-than-or-equal operator for the 
  231.  Gen_String 
  232. class. This 
  233. function returns \f3TRUE\f1 if the general string object is lexically greater than or 
  234. equal to \f2str\f1\^; otherwise, this function returns \f3FALSE\f1.
  235.  
  236. .TP
  237. \f3inline Boolean operator>= (const Gen_String& \f2str\f3) const;\f1
  238. Overloads the greater-than-or-equal operator for the 
  239.  Gen_String 
  240. class. This 
  241. function returns \f3TRUE\f1 if the general string object is lexically greater than or 
  242. equal to \f2str\f1\^; otherwise, this function returns \f3FALSE\f1.
  243. .TP
  244. \f3inline char operator[] (long \f2position\f3) const;\f1
  245. Returns the character at the zero-relative index
  246.  position 
  247. into the general 
  248. string. If an invalid index is specified, an 
  249.  \f3\f3Error\f1\f1 
  250. exception is raised.
  251. .TP
  252.  inline operator char* () const;
  253. Provides an implicit conversion operator to convert a string object into a 
  254.  char* 
  255. value.
  256. .TP
  257. \f3Boolean remove (long \f2start\f3, long \f2end\f3);\f1
  258. Removes the sequence of characters between the zero-relative inclusive 
  259.  start 
  260. and exclusive 
  261.  end 
  262. indexes provided. This function returns \f3TRUE\f1 if successful; 
  263. otherwise, this function returns \f3FALSE\f1 if either one or both of the indexes is 
  264. out of range.
  265. .TP
  266. \f3Boolean replace (const char* \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  267. Replaces the sequence of characters between the zero-relative inclusive 
  268.  start 
  269. and exclusive 
  270.  end 
  271. indexes with a copy of the character string 
  272.  str . 
  273. This function returns \f3TRUE\f1 if successful; otherwise, this function returns \f3FALSE \f1if 
  274. either one or both of the indexes is out of range.
  275. .TP
  276. \f3void resize (long \f2size\f3);\f1
  277. Resizes the general string object to hold at least
  278.  size 
  279. characters. If a 
  280. negative size is specified, an 
  281.  \f3\f3Error\f1\f1 
  282. exception is raised.
  283. .TP
  284.  void reverse ();
  285. Reverses the ordering of the characters in a general string object.  The 
  286.  Reg_Exp 
  287. does not need to be recompiled.
  288. .TP
  289. \f3inline void set_alloc_size (int \f2size\f3);\f1
  290. Updates the allocation growth size to be used when the growth ratio is zero. 
  291. Default allocation growth size is 100 bytes. If a negative size is specified, 
  292. an 
  293.  \f3\f3Error\f1\f1 
  294. exception is raised.
  295. .TP
  296. \f3inline void set_growth_ratio (float \f2ratio\f3);\f1
  297. Updates the growth ratio for this instance of a 
  298.  Gen_String 
  299. class object to the 
  300. specified value. When a string needs to grow, the current size is multiplied by 
  301. the ratio to determine the new size. If a negative growth ratio is specified, 
  302. an 
  303.  \f3\f3Error\f1\f1 
  304. exception is raised.
  305. .TP
  306.  inline long start () const;
  307. Returns an index into the last string successfully searched for by that object. 
  308.  The index corresponds to the beginning of the last item found.
  309. .TP
  310. \f3void sub_string (Gen_String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  311. Sets the general string object 
  312.  str 
  313. to the values of the character sequence 
  314. between the zero-relative inclusive 
  315.  start 
  316. and exclusive 
  317.  end 
  318. indexes provided. 
  319. This function returns \f3TRUE\f1 if successful; otherwise, if the start or end 
  320. indexes or both are out of range, an 
  321.  \f3\f3Error\f1\f1 
  322. exception is raised and, if the 
  323. handler returns, this function returns \f3FALSE\f1.
  324. .TP
  325. \f3void yank (Gen_String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  326. Deletes the sequence of characters between the zero-relative inclusive 
  327.  start 
  328. and exclusive 
  329.  end 
  330. indexes provided and sets the string object 
  331.  str 
  332. to the value 
  333. of the deleted characters. If the start or end or both indexes are out of 
  334. range, an 
  335.  \f3\f3Error\f1\f1 
  336. exception is raised.
  337.  
  338. .SH Friend Functions
  339. .TP
  340. \f3inline friend double atof (const Gen_String& \f2str\f3);\f1
  341. Returns the floating-point value represented by the characters in the general 
  342. string object \f2str\f1. 
  343. .TP
  344. \f3friend int atoi (const Gen_String& \f2str\f3);\f1
  345. Returns the decimal radix integer number represented by the characters in the 
  346. general string object 
  347.  str .
  348. .TP
  349. \f3friend long atol (const Gen_String& \f2str\f3);\f1
  350. Returns the decimal radix long number represented by the characters in the 
  351. general string object 
  352.  str .
  353. .TP
  354. \f3friend Gen_String& capitalize (Gen_String& \f2str\f3);\f1
  355. Capitalizes each word and returns the modified general string \f2str\f1. A word is 
  356. defined to be any subsequence of alphanumeric characters, but it must start 
  357. with a letter.  This function returns a reference to the modified general 
  358. string.
  359. .TP
  360. \f3friend Gen_String& downcase (Gen_String& \f2str\f3);\f1
  361. Converts any alphabetic character to lowercase. This function returns a 
  362. reference to the modified general string 
  363.  str .
  364. .TP
  365. \f3friend Gen_String& left_trim (Gen_String& \f2str1\f3, const char* \f2str2\f3);\f1
  366. Removes any prefix occurrence of the character string 
  367.  str2 
  368. in the general string object 
  369.  str1 . 
  370. This function returns ta reference to the modified general string 
  371.  str1 .
  372. .TP
  373. \f3friend ostream& operator<< (ostream& \f2os\f3, const Gen_String& \f2str\f3);\f1
  374. Overloads the output operator for a reference to a general string object.
  375. .TP
  376. \f3inline friend ostream& operator<< (ostream& \f2os\f3, const Gen_String* \f2str\f3);\f1
  377. Overloads the output operator for a pointer to a general string object.
  378. .TP
  379. \f3friend Gen_String& right_trim (Gen_String& \f2str1\f3, const char* \f2str2\f3);\f1
  380. Removes any suffix occurrence of the character string 
  381.  str2 
  382. in the general string object 
  383.  str1 . 
  384. This function returns a reference to the modified general string 
  385.  str1 .
  386. .TP
  387. \f3friend Gen_String& strcat (Gen_String& \f2str\f3, char \f2c\f3);\f1
  388. Concatenates a single character 
  389.  c 
  390. to a general string object 
  391.  str . 
  392. This function 
  393. returns a reference to the modified general string 
  394.  str .
  395. .TP
  396. \f3friend Gen_String& strcat (Gen_String& \f2str1\f3, const char* \f2str2\f3);\f1
  397. Concatenates a copy of the character string 
  398.  str2 
  399. to a general string object 
  400.  str1 . 
  401. This function returns a reference to the modified general string 
  402.  str1 .
  403. .TP
  404. f\f3riend Gen_String& strcat (Gen_String& \f2str1\f3, const Gen_String& \f2str2\f3);\f1
  405. Concatenates one general string object 
  406.  str2 
  407. to another general string object 
  408.  str1 . 
  409. This function returns a reference to the modified general string 
  410.  str1 .
  411. .TP
  412. \f3friend char* strchr (const Gen_String& \f2str\f3, char \f2c\f3);\f1
  413. Overloads the forward character-search function to scan from left to right 
  414. through a general string object 
  415.  str 
  416. for the first occurrence of a specific 
  417. character 
  418.  c . 
  419. This function returns a pointer to the character if found; 
  420. otherwise, this function returns 
  421.  
  422.  NULL .
  423. .TP
  424. \f3friend Gen_String& strcpy (Gen_String& \f2str\f3, char \f2c\f3);\f1
  425. Returns the result of copying a single character into a general string  object 
  426.  str .  
  427. This function returns a reference to the modified general string object 
  428.  str .
  429. .TP
  430. \f3friend Gen_String& strcpy (Gen_String& \f2str1\f3, const char* \f2str2\f3);\f1
  431. Copies a character string 
  432.  str2 
  433. into a general string object 
  434.  str1 . 
  435. This function 
  436. returns a reference to the modified general string object 
  437.  str1 .
  438.  
  439. .TP
  440. \f3friend Gen_String& strcpy (Gen_String& \f2str1\f3, const Gen_String& \f2str2\f3);\f1
  441. Copies one general string object 
  442.  str2 
  443. into another general string object 
  444.  str1 . 
  445. This function returns a reference to the modified general string object 
  446.  str1 .
  447. .TP
  448. \f3inline friend long strlen (const Gen_String& \f2str\f3);\f1
  449. Returns the number of characters (length) of the general string 
  450.  str .
  451. .TP
  452. \f3friend Gen_String& strncat (Gen_String& \f2str1\f3, const char* \f2str2\f3, int \f2n\f3);\f1
  453. Concatenates some number of characters \f2n\f1 from a character string 
  454.  str2 
  455. to a general string object 
  456.  str1 . 
  457. This function returns a reference to the modified 
  458. general string object \f2str1\f1. If a negative length is specified, an 
  459.  \f3\f3Error\f1\f1 
  460. exception is raised.
  461. .TP
  462. \f3friend Gen_String& strncat (Gen_String& \f2str1\f3, const Gen_String& \f2str2\f3, int \f2n\f3);\f1
  463. Concatenates some number of characters \f2n\f1 from one general string object 
  464.  str2 
  465. to another general string object 
  466.  str1 . 
  467. This function returns a reference to the modified general string object 
  468.  str1 . 
  469. If a negative length is specified, an 
  470.  \f3\f3Error\f1\f1 
  471. exception is raised.
  472. .TP
  473. \f3friend Gen_String& strncpy (Gen_String& \f2str1\f3, const char* \f2str2\f3, long \f2n\f3);\f1
  474. Copies some number of characters \f2n\f1 from the character string \f2str2\f1 into the general string object \f2str1\f1. This function returns a reference to the modified 
  475. general string object \f2str1\f1. If a negative number is specified, an 
  476.  \f3\f3Error\f1\f1 
  477. exception is raised.
  478. .TP
  479. \f3friend char* strrchr (const Gen_String& \f2str\f3, char \f2c\f3);\f1
  480. Overloads the backward character-search function to scan from right to left 
  481. through a general string object \f2str\f1 for the last occurrence of a specific 
  482. character \f2c.\f1 This function returns a pointer to the character if found; 
  483. otherwise, this function returns \f3NULL\f1.
  484. .TP
  485. \f3friend double strtod (const Gen_String& \f2str\f3, char** \f2ptr\f3 = \f3NULL\f3);\f1
  486. Returns the double floating-point value represented by the characters in the 
  487. general string object 
  488.  str . 
  489. If the second argument is non-zero, it is set to the 
  490. character terminating the converted string value.
  491. .TP
  492. \f3friend long strtol (const Gen_String& \f2str\f3, char** \f2ptr\f3 = NULL, int \f2radix \f1= 10\f3);\f1
  493. Returns the long number represented by the characters in the general string 
  494. object \f2str\f1. If no specific radix is specified, the default radix is decimal. If the second argument is non-zero, it is set to the character terminating the converted string value.
  495. .TP
  496. \f3friend Gen_String& trim (Gen_String& \f2str1\f3, const char* \f2str2\f3);\f1
  497. Removes any occurrence of the character string \f2str2\f1 in the general string 
  498. object \f2str1.\f1 This function returns a reference to the modified general string 
  499. \f2str1\f1.
  500. .TP
  501. \f3friend Gen_String& upcase (Gen_String& \f2str\f3);\f1
  502. Converts any alphabetic character to uppercase. This function returns a 
  503. reference to the modified general string \f2str\f1.
  504. .SH COPYRIGHT
  505.  
  506. Copyright (C) 1991 Texas Instruments Incorporated.
  507.  
  508. Permission is granted to any individual or institution to use, copy, modify,
  509. and distribute this software, provided that this complete copyright and
  510. permission notice is maintained, intact, in all copies and supporting
  511. documentation.
  512.  
  513. Texas Instruments Incorporated provides this software "as is" without
  514. express or implied warranty.
  515.  
  516.